home *** CD-ROM | disk | FTP | other *** search
/ Windows Game Programming for Dummies (2nd Edition) / WinGamProgFD.iso / mac / DirectX SDK / DXSDK / samples / Multimedia / DirectMusic / PlayAudio / readme.txt < prev    next >
Text File  |  2001-10-10  |  7KB  |  136 lines
  1. //-----------------------------------------------------------------------------
  2. // 
  3. // Sample Name: PlayAudio Sample
  4. // 
  5. // Copyright (c) 1999-2001 Microsoft Corporation. All rights reserved.
  6. //
  7. // GM/GS« Sound Set Copyright ⌐1996, Roland Corporation U.S.
  8. // 
  9. //-----------------------------------------------------------------------------
  10.  
  11.  
  12.  
  13. Description
  14. ===========
  15.   The PlayAudio sample shows how to load a segment and play it on an 
  16.   audiopath, how to use DirectMusic notifications, and how to change 
  17.   global performance parameters.
  18.   
  19. Path
  20. ====
  21.   Source: DXSDK\Samples\Multimedia\DirectMusic\PlayAudio
  22.  
  23.   Executable: DXSDK\Samples\Multimedia\DirectMusic\Bin
  24.  
  25. User's Guide
  26. ============
  27.   Play the default segment, or load another wave, MIDI, or DirectMusic 
  28.   Producer segment file by clicking Segment File. Adjust the tempo and 
  29.   volume by using the sliders
  30.   
  31. Programming Notes
  32. =================
  33.   This and other DirectMusic samples uses the DirectMusic sample 
  34.   framework, CMusicManager and CMusicSegment to help encapsulate some of 
  35.   the common functionality of DirectMusic.  The framework is contained 
  36.   in dmutil.cpp.
  37.   
  38.   This is how the sample works:
  39.   
  40.   * Upon WM_INITDIALOG.  See OnInitDialog()
  41.         1. Create a Win32 event, g_hDMusicMessageEvent.  This will be 
  42.            used by DirectMusic to signal the app whenever a DirectMusic 
  43.            notification comes in.
  44.         2. Create a help class CMusicManager called g_pMusicManager.  
  45.         3. Initialize the CMusicManager class.  This does the following. 
  46.            See CMusicManager::Initialize() in dmutil.cpp
  47.                 - Creates a IDirectMusicLoader8 using CoCreateInstance
  48.                 - Creates a IDirectMusicPerformance8 using CoCreateInstance
  49.                 - Calls IDirectMusicPerformance8::InitAudio to init DirectMusic 
  50.                   using a standard audio path.
  51.         4. Call IDirectMusicPerformance8::AddNotificationType() passing in 
  52.            GUID_NOTIFICATION_SEGMENT. This will make DirectMusic tell us about any 
  53.            segment notifications that come in.  This is needed to by this
  54.            sample to know when the segment has ended.  However DirectMusic
  55.            games may not care when the segment has ended.           
  56.         5. Call IDirectMusicPerformance8::SetNotificationHandle() passing
  57.            in the Win32 event, g_hDMusicMessageEvent.  This tells DirectMusic
  58.            to signal this event when a notification is available.
  59.  
  60.   * Setting up the app message loop.  See WinMain()
  61.         1. Create the dialog using CreateDialog().  
  62.         2. In a loop call MsgWaitForMultipleObjects() passing in 
  63.            g_hDMusicMessageEvent.  This will tell us when g_hDMusicMessageEvent
  64.            is signaled.  Above we have told DirectMusic to signal this event 
  65.            whenever a DirectMusic notification has come in.
  66.         3. If WAIT_OBJECT_0 is returned, then call ProcessDirectMusicMessages(),
  67.            See below for details.
  68.         4. If WAIT_OBJECT_0 + 1 is returned, then Windows msgs are available, so
  69.            do standard msg processing using PeekMessage().
  70.            
  71.   * When "Open File" is clicked.  See OnOpenSoundFile()
  72.         1. Get the file name from using GetOpenFileName().
  73.         2. Release the any old g_pMusicSegment.
  74.         3. Call CMusicManager::CollectGarbage().  See dmutil.cpp.
  75.            This calls IDirectMusicLoader8::CollectGarbage which 
  76.            collects any garbage from any old segment that was present.  
  77.            This is done because some sophisticated segments, in particular 
  78.            ones that include segment trigger tracks or script tracks, may 
  79.            have a cyclic reference. For example, a segment trigger that 
  80.            references another segment that references the first segment, also 
  81.            via a segment trigger track.
  82.         4. Call CMusicManager::SetSearchDirectory(). See dmutil.cpp
  83.            This calls IDirectMusicLoader8::SetSearchDirectory() 
  84.            passing in the GUID_DirectMusicAllTypes and a directory.
  85.            This will tell DirectMusic where to look for files that 
  86.            are referenced inside of segments.
  87.         5. Call CMusicManager::CreateSegmentFromFile() to create a
  88.            CMusicSegment called g_pMusicSegment from the file.  
  89.            See dmutil.cpp.  This does the following:
  90.                 - Calls IDirectMusicLoader8::LoadObjectFromFile() to 
  91.                   load the IDirectMusicSegment8 into pSegment.
  92.                 - Creates CMusicSegment passing in pSegment.
  93.                 - If the file is a pure MIDI file then it calls 
  94.                   IDirectMusicSegment8::SetParam passing in 
  95.                   GUID_StandardMIDIFile to DirectMusic this.  This makes 
  96.                   sure that patch changes are handled correctly.                  
  97.                 - If requested, it calls IDirectMusicSegment8::Download()
  98.                   this will download the segment's bands to the synthesizer.  
  99.                   Some apps may want to wait before calling this to because 
  100.                   the download allocates memory for the instruments. The 
  101.                   more instruments currently downloaded, the more memory 
  102.                   is in use by the synthesizer.
  103.                   
  104.    * When "Play" is clicked.  See OnPlayAudio()
  105.         1. If the UI says the sound should be looped, then call 
  106.            CMusicSegment::SetRepeats passing in DMUS_SEG_REPEAT_INFINITE,
  107.            otherwise call CMusicSegment::SetRepeats passing in 0.
  108.         2. Call CMusicSegment::Play() which calls 
  109.            IDirectMusicPerformance8::PlaySegmentEx().  See dmutil.cpp.
  110.         
  111.    * Upon a DirectMusic notification. See ProcessDirectMusicMessages().
  112.         This sample wants to know if the primary segment has stopped playing
  113.         so it can updated the UI so tell the user that they can play 
  114.         the sound again. This is rather complex, but typically apps 
  115.         will not need this functionality.  Here is what has to be done:
  116.         
  117.         1. Call IDirectMusicPerformance8::GetNotificationPMsg() in a loop
  118.            to process each PMsg that has occurred.
  119.         2. Switch off the pPMsg->dwNotificationOption.  This sample 
  120.            only handles it if its a DMUS_NOTIFICATION_SEGEND.  This tells 
  121.            us that segment has ended.
  122.         3. Call QueryInterface on the pPMsg->punkUser, quering for a 
  123.            IDirectMusicSegmentState8.
  124.         4. Using the IDirectMusicSegmentState8, call GetSegment to 
  125.            get a IDirectMusicSegment* of the segment it refers to.  
  126.            This call may fail is the segment may have gone away before this
  127.            notification was handled.
  128.         5. Call QueryInterface IDirectMusicSegment to get a IDirectMusicSegment8
  129.         6. Compare this pointer to the IDirectMusicSegment8 pointer 
  130.            in g_pMusicSegment, to see if this was the primary segment.
  131.            This may not always be the case since segments can have segments enbedded
  132.            inside of them, we only want handle when the primary segment has
  133.            stopped playing.  If it has, then update the UI
  134.         7. Cleanup all the interfaces.
  135.         
  136.